<h2>DESCRIPTION</h2>

<em>r.covar</em> outputs a covariance/correlation matrix for user-specified
raster map layer(s).  The output can be printed, or saved by redirecting
output into a file.

<p>
The output is an N x N symmetric covariance (correlation) matrix, 
where N is the number of raster map layers specified on the command line. 

<h2>NOTES</h2>

This module can be used as the first step of a principle components 
transformation. 
The covariance matrix would be input into a system which determines 
eigen values and eigen vectors. An NxN covariance matrix would result in 
N real eigen values and N eigen vectors (each composed of N real numbers). 

<p>
The module <em><a href="https://grasswiki.osgeo.org/wiki/AddOns/GRASS_7/misc#m.eigensystem">m.eigensystem</a></em>
in <a href="https://grass.osgeo.org/download/addons/">GRASS GIS Addons</a>
can be compiled and used to generate the eigen values and vectors.

<h2>EXAMPLE</h2>

<!--
For example (North Carolina sample dataset),

<div class="code"><pre>
g.region raster=elev_ned_30m -p
r.covar -r map=elevation,elev_ned_30m,elev_srtm_30m
</pre></div>
-->

For example, 

<div class="code"><pre>
g.region raster=layer.1 -p
r.covar -r map=layer.1,layer.2,layer.3
</pre></div>

would produce a 3x3 matrix (values are example only): 

<div class="code"><pre>
     1.000000  0.914922  0.889581
     0.914922  1.000000  0.939452
     0.889581  0.939452  1.000000
</pre></div>

In the above example, the eigen values and corresponding eigen vectors 
for the covariance matrix are: 

<div class="code"><pre>
component   eigen value               eigen vector
    1       1159.745202   &lt;0.691002  0.720528  0.480511&gt;
    2          5.970541   &lt;0.711939 -0.635820 -0.070394&gt;
    3        146.503197   &lt;0.226584  0.347470 -0.846873&gt;
</pre></div>

The component corresponding to each vector can be produced using 
<em><a href="r.mapcalc.html">r.mapcalc</a></em>
as follows: 

<div class="code"><pre>
r.mapcalc "pc.1 = 0.691002*layer.1 + 0.720528*layer.2 + 0.480511*layer.3" 
r.mapcalc "pc.2 = 0.711939*layer.1 - 0.635820*layer.2 - 0.070394*layer.3" 
r.mapcalc "pc.3 = 0.226584*layer.1 + 0.347470*layer.2 - 0.846873*layer.3"
</pre></div>

Note that based on the relative sizes of the eigen values, 
<em>pc.1</em>
will contain about 88% of the variance in the data set, 
<em>pc.2</em>
will contain about 1% of the variance in the data set, and 
<em>pc.3</em>
will contain about 11% of the variance in the data set. 

Also, note that the range of values produced in 
<em>pc.1</em>, <em>pc.2</em>, and <em>pc.3</em> will 
not (in general) be the same as those for 
<em>layer.1</em>, <em>layer.2</em>, and <em>layer.3</em>.
It may be necessary to rescale 
<em>pc.1</em>, <em>pc.2</em> and <em>pc.3</em> to 
the desired range (e.g. 0-255). 
This can be done with <em><a href="r.rescale.html">r.rescale</a></em>.

<h2>SEE ALSO</h2>

<em>
<a href="i.pca.html">i.pca</a>,
<a href="m.eigensystem.html">m.eigensystem</a> (Addon),
<a href="r.mapcalc.html">r.mapcalc</a>,
<a href="r.rescale.html">r.rescale</a>
</em>

<h2>AUTHOR</h2>

Michael Shapiro, U.S. Army Construction Engineering Research Laboratory

<!--
<p>
<i>Last changed: $Date$</i>
-->
